home *** CD-ROM | disk | FTP | other *** search
/ Mac-Source 1994 July / Mac-Source_July_1994.iso / C and C++ / System / HotKeys / HotKeys.doc < prev    next >
Encoding:
Text File  |  1993-11-30  |  4.9 KB  |  169 lines  |  [TEXT/KAHL]

  1. ----------------------------------------------------------------------------
  2.                              H o t K e y s   1 . 0
  3.  
  4.                                By Robert S. Mah
  5.                                 rmah@panix.com
  6.  
  7.                              ©1993 One Step Beyond
  8. ----------------------------------------------------------------------------
  9.  
  10.  
  11. ------------
  12. Introduction
  13. ------------
  14.  
  15. I was writing an extension, and I needed hot key support.  No problem, I 
  16. thought, it's been done dozens of times, there must be a library out there
  17. somewhere on the net.  
  18.  
  19. sumex, umich, wuarchive, ics.uci, snippets, macdev...  Nada.  Zilch.
  20.  
  21. Oh well, I thought, I guess I'll have to write my own.  Hmm, why not make it
  22. available to the rest of the world?  That way, as more folks use it, I can 
  23. be sure that the bugs are out and get rich and famous too!  OK, nix the last
  24. part.
  25.  
  26. So here it is.  Version 1.0, shiny and new.  Ready and rearin' to go!
  27.  
  28. If you use this HotKeys, please, please, let me know via e-mail.  One quick
  29. message and you'll be kept up to date on the latest versions and bug fixes.
  30.  
  31.  
  32. ------------
  33. This Package
  34. ------------
  35.  
  36. Since you're a programmer, no installation instructions are given.
  37.  
  38. The package consists of:
  39.     HotKeys.c            // implementation file
  40.     HotKeys.h            // interface file
  41.     HotKeys.rsrc        // required resources
  42.     HotKeys.π            // example project file
  43.     Test.c                // example test file
  44.     HotKeys.π.rsrc        // resources for example project file
  45.     HotKeys.doc            // this file
  46.  
  47.  
  48. -------------
  49. Using HotKeys
  50. -------------
  51.  
  52. The Functions:
  53.     
  54.     short IsHotKey( const HotKey*, const long msg, const short mods );
  55.     
  56.         Returns 1 if the event message and modifier flags match the given
  57.         hot key.  This should be called when a keyDown event has been
  58.         pulled from the event queue.
  59.     
  60.     
  61.     void SetHotKey( HotKey*, const long msg, const short mods );
  62.     
  63.         Sets the given hot key to match the event message and mods passed
  64.         in the other two params.
  65.     
  66.     void ClearHotKey( HotKey* );
  67.         
  68.         Unsets the specified to nothing.  Note that this function does NOT
  69.         clear out the fields in the structure, it only sets the onOff flag
  70.         to false.
  71.     
  72.     void SetHotKeyDlog( HotKey* );
  73.         
  74.         Provides a simple user interface so the user can set the hot key.
  75.         Note that this provides no protection against single character hot
  76.         keys.  That is application dependent.
  77.     
  78.     OSErr DrawHotKey( const HotKey*, const Rect* );
  79.     
  80.         Call this to draw the graphical representation of the given hot
  81.         key.  Much of the code in HotKeys.c is devoted to implementing
  82.         this function.
  83.  
  84. The Resources:
  85.     
  86.     DLOG/DITL (id = 1024)
  87.  
  88.         The dialog template used by SetHotKeyDlog().
  89.         
  90.     SICN (id = 1024)
  91.  
  92.         This contains the pictures for the modifier keys and a few non-
  93.         printable characters (e.g. delete, fwd delete).
  94.  
  95.     STR# (id = 1024    
  96.         
  97.         This contains strings that stand in for non-printable characters
  98.         (e.g. "return", "esc" and "F1").
  99.     
  100.     If you change the id's of these resources, be sure to change the 
  101.     globals, gHotKeySICNRsrcID, gHotKeyDLOGRsrcID, and gHotKeyStrsRsrcID
  102.     to match the new resource IDs.
  103.     
  104. Customization:
  105.     
  106.     At present, the only real simple level of customization is by modifying
  107.     the static data tables named sicnKeys and strKeys.  These contain the
  108.     virtual keycodes that are used to determine which small icon or stand-in
  109.     string to draw in place of that keycode.  
  110.     
  111.     By changing these tables, and updating the SICN and STR# resources, you
  112.     can change how keycodes are drawn.
  113.  
  114.  
  115. ---------------
  116. Version History
  117. ---------------
  118.  
  119. Version:    1.0
  120. Date:        29 Nov 1993
  121. Notes:        Finished first version.
  122.  
  123.  
  124. ----------------------------------
  125. Problems, Suggestions & The Future
  126. ----------------------------------
  127.  
  128. If you have any problems or suggestions, please let me know.  Again, don't
  129. forget to e-mail me if you use HotKeys so that I can send bug fixes and 
  130. new versions out to you.
  131.  
  132. "But it's so full featured," you say, "what could possibly be needed?"
  133.  
  134. Well, I may add support for either (or both) an event filter that processes
  135. hot keys, so that you can easily add hot keys to your extension.  And two,
  136. a way to use these neat-o, configurable, hot keys in your app's menus.
  137.  
  138. Anyone have any other ideas?
  139.  
  140. I can be reached at:    Robert S. Mah
  141.                         One Step Beyond    
  142.                         
  143.                         Telephone: 212-947-6507
  144.                         Fax:       212-563-7192    
  145.                         
  146.                         Internet:  rmah@panix.com
  147.                         CIS:       72511,421
  148.                         AppleLink: rmah
  149.                         AOL:       rmah
  150.  
  151.  
  152. -----------
  153. Legal Stuff
  154. -----------
  155.  
  156. This software is protected under U.S. and international copyright laws.
  157.  
  158. Software may be included in any non-commercial software package free of 
  159. charge as long as proper copyright notification is given.
  160.  
  161. Proper copyright notification is defined as something similar to "Hot key 
  162. support ©1993 One Step Beyond" in both documentation and any "about box".
  163.  
  164. Software may be copied and distributed either in its entirety (as defined 
  165. in "The Package" above) or as part of another software package.
  166.  
  167. For other forms of distribution, contact the author.
  168.  
  169.